SGI Freeware 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_hylafax.idb / usr / freeware / catman / u_man / cat1 / faxmail.Z / faxmail

Wrap

Text File | 2002-07-08 | 25KB | 506 lines

FAXMAIL(1) FAXMAIL(1) NNAAMMEE faxmail - _H_y_l_a_F_A_X mail-to-fax gateway application SSYYNNOOPPSSIISS ffaaxxmmaaiill [ _o_p_t_i_o_n_s ] [ _d_e_s_t_i_n_a_t_i_o_n [ _f_r_o_m ] ] DDEESSCCRRIIPPTTIIOONN _f_a_x_m_a_i_l takes an electronic mail message on standard input and converts it to POSTSCRIPT in a form that is suitable for transmission as a facsimile. The converted document is either written to the standard output or, if direct delivery is enabled, it is submitted directly to a _H_y_l_a_F_A_X server for transmission. _f_a_x_m_a_i_l is designed for use in constructing electronic mail to facsimile gateway services. For example, mail aliases may be created to automatically transmit elec tronic mail; e.g. sam: "|${BIN}/faxmail -d sam@5551212" or _f_a_x_m_a_i_l may be used as a ``mail transport agent'', extracting the necessary delivery information directly from the envelope of the mail message. If _f_a_x_m_a_i_l is invoked without enabling direct delivery then it just formats the mail message on the standard input and writes the result to the standard output. To enable direct delivery the --dd option must be specified on the command line; see below for more information. FFOORRMMAATTTTIINNGG _f_a_x_m_a_i_l formats a mail message according to the following rules: First it parses the envelope information interpret ing any meta-header information (see below) that is pre sent. Once the entire envelope has been collected it emits a formatted set of header lines. By default all header information except the ``From'', ``To'', ``Cc'', ``Subject'', and ``Date'' lines are discarded. Header lines that are kept have the _t_a_g (the string to the left of the ``:'') set in a _b_o_l_d _f_o_n_t and the _v_a_l_u_e (the string to the right of the ``:'') set in an _i_t_a_l_i_c _f_o_n_t. Mail messages that conform to the Multipurpose Internet Mail Extensions (MIME) specification are parsed and handled according to the rules given below. Plain text body parts of a mail message are formatted in a _t_e_x_t _f_o_n_t with any long lines wrapped at word boundaries unless the --cc option has been specified. By default, _f_a_x_m_a_i_l sets all text in 10 point type on an 8.5" by 11" portrait-oriented page with .35" top margin, .25" bottom margin and .25" left and right hand margins. There are command-line options to control the point size, page dimensions, orientation, and multi-column formatting. Text formatting can also be controlled through meta-header directives placed in the envelope of the mail message. EENNVVEELLOOPPEE PPRROOCCEESSSSIINNGG _f_a_x_m_a_i_l pre-processes the envelope information (i.e. the header lines) before formatting the message contents. Header lines whose names begin with ``X-FAX-'' (case- insensitive) are handled specially-they are treated as command directives that specify how to generate the resultant POSTSCRIPT or, optionally, how to deliver the resulting document as facsimile. The set of known meta- headers corresponds to the set of configuration parameters defined below. A meta-header is specified as ``X-FAX- _p_a_r_a_m_e_t_e_r'' where _p_a_r_a_m_e_t_e_r is the name of a configuration parameter; e.g. ``X-FAX-TabStop'' to set the number of spaces between tab stops. Controls for specifying headers to be passed through in the formatted text identify not only which headers but also the order in which the headers should be emitted. _f_a_x_m_a_i_l initializes the set of headers to retain to: ``To From Subject Cc Date''. If this order is acceptable then additional headers can simply be added with the X-FAX- Headers directive; e.g. ``X-FAX-Headers: Message-id''. If however a different order is desired then the header set should be cleared with a ``clear'' header tag and then completely specified in the desired order; for example, X-FAX-Headers: clear Message-id Date To Subject From Cc will cause headers to be emitted in the order ``Message-Id Date To Subject From Cc'' (depending on what headers are present). Note in particular that all header lines in the envelope can be suppressed by specifying ``X-FAX-Headers: clear''; this is useful, for example, when the body of the mail message contains a preformatted document that is to be transmitted. In addition to the above controls, _f_a_x_m_a_i_l can also be instructed to substitute an arbitrary string for a header tag when generating the final envelope. This facility can be used to better format ad-hoc header information that is passed through the envelope of the message. The ``X-FAX- MapHeader'' meta-header specifies how to map a header line. For example, X-FAX-MapHeader: x_FAX_For Deliver FAX To would cause any header ``x_FAX_For'' that appeared in the envelope to be replaced in the formatted envelope by ``Deliver FAX To''. MMIIMMEE PPRROOCCEESSSSIINNGG _f_a_x_m_a_i_l parses MIME mail messages and does some rudimen tary work to: strip out unprintable content such as audio, video, or binary data, decode encoded parts, insert ``digest dividers'' between multipart/digest subparts, format message/rfc822 parts as described above for the top-level envelope, and optionally convert graphical parts (e.g. images) for display. MIME processing is fairly simple and (currently) somewhat constrained. _f_a_x_m_a_i_l has builtin support for the follow ing MIME parts: text/plain, multipart/mixed, multi part/digest, message/rfc822, application/postscript, and application/x-faxmail-prolog. Parts can also be processed through external processing scripts that _f_a_x_m_a_i_l looks for in a ``MIME converters'' directory hierarchy. External scripts may override builtin processing or supplement the builtin support. For each MIME body part with type _T and subtype _S _f_a_x_m_a_i_l checks first for an executable script named T/S in the converter hierarchy. If a script exists then it is run and the result is appended to the output PostScript document. Otherwise if the part has builtin support then it is processed directly. Any part that does not have external or builtin support is discarded and replaced by a message that indicates the part was removed. This discarded message can be suppressed with the _M_a_r_k_D_i_s_ _c_a_r_d_e_d configuration parameter (also settable with an X- FAX-MarkDiscarded line in the envelope). The builtin handling support is as follows: text/plain parts are formatted using the default _t_e_x_t _f_o_n_t and point size; multipart/mixed are ``burst'' and interpreted per the specification but are otherwise unformatted; multi part/digest are burst and an optional ``digest divider'' marking may be inserted before each subpart; mes sage/rfc822 are formatted as described above with envelope header lines culled and formatted with bold and italic fonts (in addition, if there is insufficient space in the current output page/column for the message envelope, optional divider, and one line of text, then _f_a_x_m_a_i_l will insert a ``break'' so the the message starts at the top of the next page/column); application/postscript are copied through untouched to the output; application/x-faxmail- prolog are copied through untouched to the end of the pro logue section of the generated PostScript document to per mit customization of the formatted output. _f_a_x_m_a_i_l supports the following Content-Transfer-Encoding schemes: 7bit, 8bit, binary, base64, quoted-printable, and x-uuencode. Any character set that is not us-ascii is treated as iso-8859-1. In general it is recommended that senders either permit _f_a_x_m_a_i_l to format message contents or completely bypass the formatting facilities and submit data that is to be processed by _s_e_n_d_f_a_x. Trying to combine the two facili ties by, for example, combining PostScript with text that is to be formatted is unlikely to work well because _f_a_x_ _m_a_i_l does not track the amount of space on the page that a non-text MIME part uses. DDIIRREECCTT DDEELLIIVVEERRYY When _f_a_x_m_a_i_l is invoked with the --dd option it delivers the formatted document directly to a _H_y_l_a_F_A_X server for trans mission as facsimile. Command line arguments may be sup plied to specify the delivery destination and sender iden tity; typically from information extracted by the mail transport facility. A command line _d_e_s_t_i_n_a_t_i_o_n is speci fied with the same syntax as the argument for the --dd option to the _s_e_n_d_f_a_x(1) command. Similarly any _f_r_o_m identity specified on the command line follows the same rules as the --ff option to _s_e_n_d_f_a_x. An explicit dialstring to use in delivery can also be specified with an X-FAX- Dialstring header in the mail message envelope. If no sender identity is provided on the command line then _f_a_x_ _m_a_i_l will extract it from the ``From'' line in the enve lope. _f_a_x_m_a_i_l will not submit a message for delivery if either the dialstring or sender identity is missing or null. When direct delivery is enabled X-FAX- header lines may be included in the mail message envelope to control the sub mission and delivery process. As above these lines are specified as ``X-FAX-_p_a_r_a_m_e_t_e_r'' where _p_a_r_a_m_e_t_e_r is the name of a configuration parameter for the _s_e_n_d_f_a_x program; e.g. ``X-FAX-VRes'' to set the vertical resolution of the transmitted facsimile. By default automatic cover page generation is enabled when direct delivery is used; this can be overridden with the --nn option on the command line or by including an X-FAX-AutoCoverPage header in the mes sage envelope. OOPPTTIIOONNSS --11 Set text in one column (default). --22 Set text two columns. --bb _f_o_n_t Make _f_o_n_t, a POSTSCRIPT font name, the ``_b_o_l_d _f_o_n_t'' used to set header lines. The default bold font is Helvetica-Bold. --cc Clip long text lines instead of wrapping them at page margins. --dd Enable direct delivery of facsimile; the format ted document will be submitted directly to a _H_y_l_a_F_A_X server for transmission as facsimile. This option is similar to piping the output of _f_a_x_m_a_i_l to the input of _s_e_n_d_f_a_x(${MANNUM1_8}) except when direct delivery is enabled _f_a_x_m_a_i_l interprets ``x-fax-'' header lines in the enve lope of the mail message to look for control information to use in delivering the facsimile and, by default, no automatic cover page genera tion is done. --ff _f_o_n_t Make _f_o_n_t, a POSTSCRIPT font name, the text font used to set the body of mail messages. The default text font is Courier. --HH _h_e_i_g_h_t Use _h_e_i_g_h_t as the height, in inches, of the out put page. The default page height is taken from the default page size. --ii _f_o_n_t Make _f_o_n_t, a POSTSCRIPT font name, the ``_i_t_a_l_i_c _f_o_n_t'' used to set header lines. The default italic font is Helvetica-Oblique. --MMll==_#_,rr==_#_,tt==_#_,bb==_# Set the page margins; the default margins are: left and right .25 inch, top .35 inch, bottom .25 inch. --nn Suppress auto cover page generation when doing direct delivery. --pp _s_i_z_e Set all text using _s_i_z_e for the font point size. --rr Set pages rotated by 90 degrees (in ``Landscape mode''). --RR Set pages unrotated (in ``Portrait mode''). --ss _s_i_z_e Set the page size to use. Cover pages are nor mally generated using a system-default page size (usually letter-size pages, 8.5" by 11", for sites in North America). Alternate page sizes are specified symbolically using either the name or abbreviation of an entry in the _p_a_g_e_ _s_i_z_e_s(${MANNUM4_5}) database; e.g. _a_3 (ISO A3), _a_4 (ISO A4), _a_5 (ISO A5), _a_6 (ISO A6), _b_4 (ISO B4), _n_a_-_l_e_t (North American Letter), _u_s_-_l_e_g (American Legal), _u_s_-_l_e_d (American Ledger), _u_s_- _e_x_e (American Executive), _j_p_-_l_e_t (Japanese Let ter), and _j_p_-_l_e_g (Japanese Legal). Comparisons are case-insensitive and any match of a sub string of the full page-size name is sufficient; e.g. ``legal'' would match ``American Legal''. --uu _u_s_e_r Set the user name to use when logging in to do direct delivery. By default the user is speci fied by the MMaaiillUUsseerr configuration parameter (see below). If a null user name is specified, then the facsimile will be submitted using the identity of the user that invoked _f_a_x_m_a_i_l. --vv Enable tracing of envelope, MIME, and job sub mission processing. Diagnostic information is written to the standard error (envelope and MIME processing) and standard output (job submis sion). --WW _w_i_d_t_h Use _w_i_d_t_h as the width, in inches, of the output page. The default page width is taken from the default page size. CCOONNFFIIGGUURRAATTIIOONN PPAARRAAMMEETTEERRSS _f_a_x_m_a_i_l reads configuration information from the files $${{LLIIBBDDAATTAA}}//hhyyllaa..ccoonnff, and ~~//..hhyyllaarrcc; in that order. Con figuration files follow the conventions described in _h_y_l_a_f_a_x_-_c_l_i_e_n_t(1). The following configuration parameters are recognized: TTaagg TTyyppee DDeeffaauulltt DDeessccrriippttiioonn AutoCoverPage boolean Yes automatically generate cover page BoldFont string Helvetica-Bold font for setting header tags Columns integer 1 number of columns in formatted output DigestDivider string - multipart/digest divider POSTSCRIPT command FontPath string _s_e_e _b_e_l_o_w directory for font metric files GaudyHeaders boolean No enable/disable gaudy page headers Headers string _s_e_e _b_e_l_o_w headers to retain in envelope ISO8859 boolean Yes use ISO 8859-1 character encoding ItalicFont string Helvetica-Oblique font for setting header values LineWrap boolean Yes wrap/truncate text lines MailUser string - user identity for doing direct delivery MarkDiscarded boolean Yes mark discarded MIME body parts MapHeader string - define header mapping MIMEConverters string _s_e_e _b_e_l_o_w pathname of MIME converter scripts Orientation string portrait orientation of text on page OutlineMargin inches 0 width of outline line PageCollation string forward collate pages in forward or reverse direction PageHeaders boolean Yes enable/disable page headers PageHeight float - output page height PageMargins string _s_e_e _b_e_l_o_w margins for formatted page PageSize string default output page size from database PageWidth float - output page width Prologfile string _s_e_e _b_e_l_o_w pathname of POSTSCRIPT prologue file TabStop integer 8 inter-stop setting in characters TextFont string Courier name of font for setting text TextLineHeight inches - text formatting line height control TextPointSize inches _s_e_e _b_e_l_o_w size to use in setting text Verbose boolean No trace envelope and MIME processing Values marked as _i_n_c_h_e_s are specified using a syntax that identifies one of several possible units: #.##bp big point (1in = 72bp) #.##cc cicero (1cc = 12dd) #.##cm centimeter #.##dd didot point (1157dd = 1238pt) #.##in inch #.##mm millimeter (10mm = 1cm) #.##pc pica (1pc = 12pt) #.##pt point (72.27pt = 1in) #.##sp scaled point (65536sp = 1pt) Unit names can be upper or lower case but no white space is permitted between the number and the unit. Values specified with no unit are interpreted as points. The configuration parameters are explained below. Most parameters correspond to a command line option. Parameter values identified above as _i_n_c_h_e_s are converted according to the conventions described above. AAuuttooCCoovveerrPPaaggee Control whether or not a cover page is automatically generated for each job. BBoollddFFoonntt The name of the font to use to set header tags (i.e. the string to the left of the ``:''). CCoolluummnnss The number of columns to set text in. (Equivalent to the --mm option.) DDiiggeessttDDiivviiddeerr The string to emit in the output before each subpart of a multipart/digest mail message. This string is typically a POSTSCRIPT procedure that draws a mark of some sort. Dividers are expected to use no more vertical space on the output page than a line of text. FFoonnttPPaatthh The path where Adobe Font Metric (AFM) files are located; by default ${FONTPATH}. GGaauuddyyHHeeaaddeerrss Control whether or not to use a gaudy-style page header. Enabling gaudy headers implicitly enables page headers. HHeeaaddeerrss Define the headers retained from the enve lope and specify the order that they should be emitted in the formatted output. The set of headers is initialized to ``To From Subject Cc Date''. Headers specified are appended to this list except for a ``clear'' header that causes the current set of headers to be discarded. IISSOO88885599 Control the use of ISO 8859-1 encoding in the generated POSTSCRIPT IIttaalliiccFFoonntt The name of the font to use to set header values (i.e. the string to the right of the ``:''). LLiinneeWWrraapp Control whether long text lines are wrapper or truncated at the right hand margin. (Equivalent to the --cc option.) MMaaiillUUsseerr The account name to use to login to a fax server when doing direct delivery. Note that this account name is not used for the identity of the sender; this comes from the command line or the ``From'' line in the mail message. If a null account name is specified, then the facsimile will be sub mitted using the identity of the user that invoked _f_a_x_m_a_i_l. MMaappHHeeaaddeerr Define a substitution for the specified header that should be done each time the header is emitted in the formatted enve lope. Header tags are matched in a case- insensitive manner. MMaarrkkDDiissccaarrddeedd Control whether discarded MIME parts are replaced by a text message indicating the original content was removed. MMIIMMEECCoonnvveerrtteerrss The pathname of a directory hierarchy that has scripts for external processing of MIME body parts. The default pathname is ${LIBEXEC}/faxmail. OOrriieennttaattiioonn Control whether pages are oriented horizon tally (``landscape'') or vertically (``por trait''). (Equivalent to the --rr and --RR options.) OOuuttlliinneeMMaarrggiinn Control whether columns of text have a line drawn around them and the width of the line. Setting this parameter to 0 disables outlines. PPaaggeeCCoollllaattiioonn Control whether the output file has pages collated in the same order as the input file (``forward'') or in reverse order (``reverse). PPaaggeeHHeeaaddeerrss Control whether page headers are generated. PPaaggeeHHeeiigghhtt Set the output page height (in inches). PPaaggeeMMaarrggiinnss Set the output page margins. Margins are specified as string of the form: ``ll==#,rr==#,tt==#,bb==#'' where ll indicates the left margin, rr indicates the right margin, tt indicates the top margin, bb indicates the bottom margin, and numbers are interpreted as _i_n_c_h_e_s. (Equvalent to the --MM option.) PPaaggeeSSiizzee Set the output page dimensions by name. (Equivalent to the --ss option.) PPaaggeeWWiiddtthh Set the output page width (in inches). PPrroollooggFFiillee The pathname of a file containing POSTSCRIPT that should be included in the prologue section of the generated POSTSCRIPT. The default prologue file is ${LIBDATA}/faxmail.ps. TTaabbSSttoopp Set the tab stop distance (in characters). TTeexxttFFoonntt Set the name of font to use for setting text. (Equivalent to the --ff option.) TTeexxttLLiinneeHHeeiigghhtt Set the vertical text line height and spac ing. TTeexxttPPooiinnttSSiizzee Set the point size to use in setting plain text. (Equvalent to the --pp option.) VVeerrbboossee Control tracing envelope and MIME process ing. NNOOTTEESS Because a sender's identity in an electronic mail message is inherently untrustworthy, using _f_a_x_m_a_i_l to build a mail to fax gateway is problematic. Unless mail service is somehow restricted or the sender's identity is verified using a mechanism such as RFC 1847's multipart/signed MIME type there is no reliable way to restrict access to facil ities setup with _f_a_x_m_a_i_l. BBUUGGSS Only the last instance of a header is kept and written to the output. This means, for example, that only the last of many ``Received'' lines will be included in the format ted output. FFIILLEESS ~/.hylarc per-user configuration file ${LIBDATA}/pagesizes page size database ${LIBDATA}/faxmail.ps POSTSCRIPT prologue ${LIBDATA}/hyla.conf system-wide configuration file ${LIBDATA}/faxmail.conf system-wide configuration file ${LIBDATA}/sendfax.conf system-wide configuration file for direct delivery ${LIBEXEC}/faxmail hierarchy for external MIME converters ${FONTPATH} for font metrics ${SPOOL}/tmp/faxmailXXXXXX temporary files SSEEEE AALLSSOO _h_y_l_a_f_a_x_-_c_l_i_e_n_t(1), _t_e_x_t_f_m_t(1), _s_e_n_d_f_a_x(1) July 22, 1996 FAXMAIL(1)